Fields Collection Object

The Fields collection object contains one or more Field objects. Field objects give you the ability to access properties of the object. These include the predefined underlying MAPI properties and your own custom user-defined properties.

Quick Info

A Fields collection is considered a small collection, which means that it supports count and index values that let you access an individual Field object through the Item property. The Fields collection supports the Visual Basic For Each statement.

Properties

Methods

Remarks

MAPI defines a set of properties with identifiers less than the value 0x8000. These are known as unnamed properties because they are usually accessed using the identifier rather than a name. You can access these MAPI-defined properties using the Fields collection. All MAPI properties are accessible except those of types PT_OBJECT and PT_CLSID.

You can also extend the properties available through MAPI by defining your own properties. These user-defined properties, defined using a name and automatically assigned an identifier value greater than 0x8000 by the OLE Messaging Library, are known as named properties. (C++ programmers can access the property name in the MAPI structure MAPINAMEID and convert it to the property tag value.)

All named properties are defined as part of a property set, which is also known in the context of the OLE Messaging Library as a namespace.

A property set is defined by a GUID, or unique identifier. The OLE Messaging Library represents this GUID as a string of hexadecimal characters. Such identifiers are usually referenced using a constant that starts with the characters PS_, such as PS_PUBLIC_STRINGS, the default property set for all properties created using the OLE Messaging Library.

You can also choose to organize your custom properties within their own semantic space by defining your own property set. The Add and SetNamespace methods and the Item property let you specify the property set identifier to be used for property access. When creating your own property set, you should be aware that MAPI reserves several property set identifiers for specific purposes. The following table lists reserved property sets:

To create your own GUID that identifies your property set, you can either use the Win32 command-line utility UUIDGEN or you can call the OLE function CoCreateGuid to supply one for you, as demonstrated in the following code:

' declarations required for the call to CoCreateGuid

Type GUID

    Guid1 As Long

    Guid2 As Long

    Guid3 As Long

    Guid4 As Long

End Type

Declare Function CoCreateGuid Lib "OLE32.DLL" (pGuid As GUID) As Long

Global Const S_OK = 0

Dim strPropID as String

Dim lResult As Long

Dim lGuid As GUID

' call CoCreateGuid, then convert the result to a hex string

    lResult = CoCreateGuid(lGuid)

    If lResult = S_OK Then

        strPropID =  Hex$(lGuid.Guid1) & Hex$(lGuid.Guid2)

        strPropID = myHexString & Hex$(lGuid.Guid3)

        strPropID = myHexString & Hex$(lGuid.Guid4)

    Else

          ... handle error...

    End If

'

Note that MAPI stores all custom properties that represent date and time information using Greenwich Mean Time (GMT). The OLE Messaging Library converts these properties so that the values appear to the user in local time.

For more information about properties and property sets, see the topic,  About Named Properties,  in the MAPI Programmer s Reference. For more information about UUIDGEN and CoCreateGuid, see the Win32 SDK documentation.

Example

To uniquely identify Field objects in the Fields collection, use the Field object s Name property or an index:

Set objOneField = objFolder.Fields.Item("BalanceDue")

Set objAnotherField = objMessage.Fields.Item("Keyword")

Set objThirdField = objMessage.Fields.Item(3)

See Also

SetNamespace Method (Fields Collection)1XBJQQ0, Object CollectionsH0P41I